home *** CD-ROM | disk | FTP | other *** search
/ Aminet 7 / Aminet 7 - August 1995.iso / Aminet / dev / misc / CIATrkrLib.lha / CIATrackerLib.doc next >
Text File  |  1995-06-23  |  6KB  |  180 lines
  1.                        CIATracker.lib Documentation
  2.  
  3.                           Previous revisions by:
  4.                                Neil O'Rourke
  5.  
  6.                           Version 1.0b (21/6/95)
  7.  
  8.  
  9.  
  10. Introduction
  11. ~~~~~~~~~~~~
  12. The standard soundtracker replay routines supplied with Blitz Basic 2 have
  13. many faults, which this library attempts to overcome.  Some of the features
  14. are:
  15.  
  16.   - Plays all NT/PT songs that utilise either the VBLANK timing or the
  17.     more recent CIA based timings
  18.   - Plays back correctly on 50/60Hz systems, running either PAL or NTSC
  19.   - Contains more specialised functions for advanced programmers
  20.   - Enables the programmer to syncronise graphics with their music
  21.  
  22.  
  23. Credits:
  24. ~~~~~~~~
  25. Original ProTracker playroutine by Amiga Freelancers, converted and
  26. enhanced for Blitz by Neil O'Rourke.  Naggings from Roy, Jeff and Richard.
  27. Newer revisions and further enhancements by Crossbones/Binary Assault.
  28.  
  29.  
  30. NOTE:
  31. ~~~~~
  32.  Neil stopped work on the library at version 1.6. Unfortunately, all the
  33. source code I've located of this library is only at version 1.3. This means
  34. that if you are fimiliar with the last version of his library, a few of the
  35. commands might not contain the same sytax or might not even be in this
  36. library any more.
  37.  
  38.  If you find that you simply can't live without a certain feature, you
  39. might try to contact me and coax me into providing the update you need. 
  40. I say *MIGHT* because there is no guarentee that I'll work on it.
  41.  
  42.  
  43. Quick Usage:
  44. ~~~~~~~~~~~~
  45. Load the module you want with the LoadTrackerModule command, and then 
  46. StartTrackerModule it.
  47.  
  48.  
  49. Basic Commands
  50. ~~~~~~~~~~~~~~
  51. success=LoadTrackerModule(TrackerModule#,FileName$)
  52.  
  53. Loads the named module into chip ram, ready for playing.  This command can
  54. only be called in Amiga mode.  success is a boolean return code (true).  If
  55. the load fails for any reason, success returns the AmigaDOS error code.
  56.  
  57. Note that there is an implicit call to FreeTrackerModule for whatever
  58. module you are trying to load.  However, if you want to load another
  59. module, don't try to load it on top of the existing one that is playing.
  60. Use another TrackerModule# (you have from 0 to 8).  The results are
  61. unpredictable, and range from nothing to a system crash.  We can't call
  62. StopTracker, because this will stop everything.
  63.  
  64.  
  65. success=StartTracker(TrackerModule#)
  66.  
  67. Starts to play the requested module, stopping any modules already playing,
  68. or restarts the current module, and returns true.  Returns false if the
  69. module couldn't be started for some reason (like it isn't loaded).
  70.  
  71.  
  72. StopTracker
  73.  
  74. Stops the current module
  75.  
  76.  
  77. FreeTrackerModule TrackerModule#
  78.  
  79. This frees a module loaded with LoadTrackerModule.  You cannot free a
  80. module that has been set up with SetTrackerModule (see below), but there is
  81. nothing to stop you trying.
  82.  
  83.  
  84. DecodeModule TrackerModule#,ModuleAddress
  85.  
  86. This sets an arbitary area of memory as a tracker module, useful if you
  87. have BLoaded/INCBIN'd a file and want to hear if it is a module. Caution: 
  88. a non-module may crash the Amiga.
  89.  
  90.  
  91. trackerlength=GetTrackerSize(TrackerModule#)  GetTrackerLocation (TrackerModule#)
  92.  
  93. Both these functions return information about the module that has been
  94. loaded with LoadTrackerModule.  There should be no need to use this
  95. information, and these commands are only included because they served a
  96. purpose in debugging a long time ago, and to remove them would cause
  97. problems with the Blitz tokens
  98.  
  99.  
  100. trackerevent=GetTrackerEvent
  101.  
  102. This command is a customised extension to the ProTracker replay routine.  A
  103. "TrackerEvent" occurs when the replay routine comes across a $8xx command.
  104. This command is not defined in the command list, and many demos (eg Jesus
  105. on E's) use it to trigger effects.  This command gets the most recent
  106. TrackerEvent, so any program looking at this will have to compare the
  107. current value to the value that triggered the current effect.
  108.  
  109.  
  110. success=CheckTrackerEvent
  111.  
  112. This routine checks to see if a TrackerEvent has occured since the last
  113. time the routine was called, and returns True if it has.  Use
  114. GetTrackerEvent to determine what data the $8xx command had.
  115.  
  116.  
  117. WaitTrackerEvent
  118.  
  119. ** V1.6: DO NOT USE THIS COMMAND! **
  120. ** V1.0b: I haven't checked this. **
  121.  
  122. success=CheckTrackerModuleID(TrackerModule#)
  123.  
  124. This checks the module for the standard Pro/Noise/SoundTracker ID string
  125. "M.K." (or "M!K!" in the case of a 100 pattern PT module), and returns True
  126. if one of them is found.  This means that you can safely call StartTracker.
  127.  
  128. Note that there is no 100% guarenteed way of determining what is a module
  129. and what isn't.  Bit Arts, for example, remove the M.K. identifier to make
  130. it harder to rip modules, so if you're writing a module ripping program,
  131. you have to take this result with a grain of salt.
  132.  
  133.  
  134. SongPos=GetModulePosition
  135.  
  136. This returns the current pattern that is playing in the song
  137.  
  138.  
  139. ModulePositionJump(Position#)
  140.  
  141.  This command tells the play routine to jump to the pattern requested in
  142. Position#.
  143.  
  144.  
  145. name$=GetModuleName$(TrackerModule#)
  146.  
  147. Returns the name of the module in name$
  148.  
  149.  
  150. success=ModuleToChip(TrackerModule#)
  151.  
  152.  This command is mainly of use for people using the INCBIN method of adding
  153. the module to the compiled program. This command reserves X amount of bytes
  154. of chipmem and moves the module (and references) to that memory location.
  155.  
  156. NOTE: This command will free any references to the module in fastmemory.
  157.       If you free the module from chipmem and need it again, you'll have
  158.       to decode it again first.
  159.  
  160.  
  161. Notes:
  162. ~~~~~~
  163. Quite a number of these commands extract their data from the playroutine in
  164. real time; that is, around fifty times a second (depending upon the tempo).
  165. Therefore, the value your program receives could well be very different
  166. from what is actually happening in the song.
  167.  
  168.  
  169. How do I contact the person revising this library?
  170. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  171.  Steve Flock [Crossbones] / Binary Assault
  172.  Email: sflock@comtch.iea.com
  173.  
  174.  Snail:
  175.  
  176.  Steve Flock
  177.  2421 west LaCrosse
  178.  Spokane, Washington
  179.  99205
  180.